「幫我改好一點」留下太多空白

開發者看到命令列噴出一整段錯誤，順手對 Codex 說：「幫我把找不到檔案時的錯誤訊息改好。」這句話指出了方向，卻沒有說明哪個操作可以重現問題、希望顯示哪些內容、允許修改哪些地方，以及完成後要用什麼方式檢查。

Codex 會閱讀專案並補足缺少的資訊。它可能自行判斷錯誤訊息、結束碼、測試範圍與修改位置。同一句「改好」，會導向數種不同結果。提示詞（Prompt）的作用，是把這些決定交代給 Codex。

我們將繼續使用 codex-hands-on 專案完成固定任務。當輸入檔案不存在時，將原始 ENOENT 堆疊改成可閱讀的錯誤訊息，並回傳結束碼 1。正常輸入、JSON 格式錯誤、議題排名與標籤統計，都要維持現有行為。

提示詞內容至少要說明目標、背景、限制與完成條件。限制可以拆成修改範圍與需要保留的行為，再補上測試命令，形成一個可以直接執行與驗收的任務。

先用重現方式補齊背景

背景要讓 Codex 知道目前發生什麼事。只貼上 ENOENT，仍缺少觸發方式，代理人很可能要在專案裡猜測是哪一段檔案讀取流程。

專案已在 package.json 定義 npm start，並於專案根目錄執行一個不存在的輸入路徑。

npm start -- ./fixtures/not-found.json

目前結果會把 Node.js 的 ENOENT 錯誤與程式堆疊印到終端機。這份背景應記錄輸入命令、觀察到的輸出與執行環境，讓 Codex 可以重跑相同操作。

背景也可以提供懷疑的檔案或函式，但不要把尚未確認的推測寫成事實。

讓 Codex 修正錯誤時，應提供重現步驟與相關檔案線索。目前只指出問題發生在命令列讀取輸入檔案時，並要求 Codex 先追蹤入口與錯誤處理位置。

這樣可以提供方向，也保留讓代理人依程式碼找出責任位置的空間。

把目標寫成可以觀察的結果

目標要描述使用者最後會看到的改變。「改善錯誤處理」可能包含記錄日誌、重新嘗試、替換訊息與調整結束碼等作法。

我們先把結果固定為：找不到輸入檔案時，在標準錯誤輸出顯示 Input file not found: <path>，其中 <path> 保留使用者傳入的路徑。

結束碼也是命令列工具對外行為的一部分。成功時回傳 0，找不到輸入檔案時回傳 1，方便腳本與持續整合流程判斷執行失敗。

輸出中不顯示 Node.js 程式堆疊，避免一般使用者看到內部函式與檔案位置。

撰寫目標時，可以直接使用可觀察的名詞，例如輸出文字、回傳值、畫面狀態或資料變化。Codex 完成後，開發者能執行重現命令，將結果與目標逐項核對。

若只描述「程式碼要乾淨」或「錯誤要友善」，驗收時仍會回到個人感受，很難判斷任務是否完成。

指定修改範圍與需要保留的行為

修改範圍告訴 Codex 可以在哪裡工作。我們能先允許它尋找命令列入口、檔案讀取位置及相關測試，再修改錯誤處理實作與直接相關測試。README、套件設定、部署檔案及其他功能則不在這次範圍內，也不需要加入新的相依套件。

範圍不必在尚未讀懂專案時硬指定要修改的位置。若開發者已確認路徑，可以直接指定檔案與函式。若尚未確認，可以用責任描述限制範圍，要求 Codex 找到位置後再修改。

這種寫法能避免提供錯誤路徑，也能阻止任務擴大成整個命令列模組的重構。

需要保留的行為要寫得具體。這次修正只處理「檔案不存在」的情境。有效 JSON 檔案仍要輸出原有排名與標籤統計，JSON 內容格式錯誤時沿用既有訊息與結束碼。

Codex 若發現這些行為沒有測試，應先說明，再補上完成本次修正所需的回歸測試。

用驗收條件定義完成狀態

驗收條件把需求轉成可以逐項確認的結果。我們需要驗證不存在的路徑會顯示指定訊息、路徑文字正確、結束碼為 1，且輸出沒有程式堆疊。同時，也要確認有效檔案與格式錯誤的既有行為沒有改變。

這些條件應反映在自動化測試中。新增測試可以從命令列入口執行不存在的路徑，分別檢查標準錯誤輸出與結束碼。現有測試則用來保護正常資料、格式錯誤、排名與標籤統計。若專案已有測試工具與寫法，Codex 應沿用相同模式。

測試命令也要直接寫入提示內容。可以指定 Codex 先執行新增或修改的相關測試，再執行 npm test。完成回覆需列出實際執行的命令、通過與失敗數量，以及任何沒有執行的檢查。

修正後應重跑錯誤重現步驟，並執行相關測試與專案的標準檢查。

將六項資訊組成完整提示詞

準備好目標、背景、範圍、保留行為、驗收條件與測試命令後，就能整理成一段完整的提示內容。

各欄位使用清楚的小標籤，可以讓開發者送出前逐段核對，也方便 Codex 完成任務時引用相同條件回報結果。

請修正 codex-hands-on 命令列工具在輸入檔案不存在時的錯誤處理。

背景：
在專案根目錄執行 npm start -- ./fixtures/not-found.json，目前終端機會顯示 Node.js 的 ENOENT 錯誤與程式堆疊。

目標：
找不到輸入檔案時，請在標準錯誤輸出顯示：
Input file not found: <path>
其中 <path> 是使用者傳入的路徑。結束碼必須為 1，輸出不要包含程式堆疊。

修改範圍：
請先找出命令列入口、檔案讀取位置與相關測試。
只修改檔案不存在的錯誤處理，以及直接相關的自動化測試。

需要保留的行為：
有效 JSON 檔案仍要輸出現有的議題排名與標籤統計。
JSON 格式錯誤時，維持現有錯誤訊息與結束碼。
不要修改 README、套件設定、部署檔案或其他功能，不要新增相依套件或建立提交。

驗收條件：
不存在的路徑會顯示指定訊息與正確路徑，結束碼為 1，且沒有程式堆疊。
正常輸入與 JSON 格式錯誤的既有測試仍然通過。
請新增一個能重現這次問題的測試。

測試方式：
先執行直接相關的測試，再執行 npm test。
完成後列出修改檔案、行為變化、實際測試命令與結果。
若現有程式與上述描述衝突，請先停止並說明衝突。

這段提示詞內容交代了任務資訊，不需要加入客套話、角色扮演或大量技術術語。

若專案中不存在 npm start 或 JSON 輸入流程，Codex 會依最後一項限制停下來回報衝突，開發者可以修正背景後再送出。

送出後檢查 Codex 如何執行

在專案根目錄開啟 Codex CLI，確認 Git 工作目錄乾淨，再貼上完整提示內容。

Codex 應先追蹤命令列入口與檔案讀取流程，找到現有錯誤處理與測試慣例，接著進行局部修改。工作紀錄若顯示它準備調整套件、README 或其他輸出，應立即提醒它回到指定範圍。

完成後先閱讀檔案清單與差異。錯誤處理只應攔截檔案不存在的情況，不能將權限不足、JSON 格式錯誤或其他讀取問題全部改成 Input file not found。

新增測試要真正執行命令列入口，檢查標準錯誤輸出、路徑與結束碼，避免只測一個和實際流程無關的輔助函式。

接著核對重現命令、相關測試與 npm test 的原始結果。若 Codex 只回覆「全部通過」，可以要求它補上命令、測試數量與略過項目。

任何測試失敗都應先查明原因；修改過實作或測試後，要重新執行完整驗證，再閱讀更新後的差異。

一份寫得清楚的提示詞仍無法取代人工審查。它可以讓 Codex 從同一組需求出發，開發者仍要確認程式的判斷條件、錯誤訊息、結束碼與測試證據，最後決定是否保留修改。

用後續訊息補充已確認的缺口

最初的提示詞不需要預測執行期間的每個細節。Codex 回報專案現況後，開發者可以補充缺少的資訊。

例如實際測試顯示 Windows 路徑格式與預期不同，就可以明確指定保留使用者輸入的原始文字，並要求只修正對應測試。

後續訊息應指出具體證據與期望變更。可以寫：「新增測試把路徑正規化成斜線，和需求不符。請保留命令列收到的原始路徑文字，只調整這項實作與測試，完成後重新執行相關測試和 npm test。」這樣 Codex 就能沿用前一輪背景，處理單一缺口。

若最初的目標、範圍或驗收條件改變，應更新完整提示內容或重新建立一項任務，避免多輪補充互相衝突。

若只是補上一個漏掉的案例，可以留在同一段對話中繼續。每次修改後仍要回到原有驗收條件，確認新指示沒有破壞先前已通過的行為。

提示內容是可以反覆校正的任務說明。第一輪提供足夠執行的資訊，後續輪次則用實際差異與測試結果收斂內容。

分清單次提示詞與專案規則

本次的完整提示詞內容只服務這次錯誤修正。重現命令、指定訊息與結束碼都屬於單次需求，任務完成後很難原樣使用。

這些內容適合保留在對話或議題紀錄中，用來說明這次修改的背景與驗收依據。

專案中長期有效的資訊適合寫入 AGENTS.md，例如專案使用 npm test、命令列錯誤寫入標準錯誤輸出、禁止讀取部署金鑰，以及提交前要執行哪些檢查。

Codex 進入專案後可以自動讀取這些規則，單次提示內容便能集中描述目前要修改的功能與限制。

兩者的內容若重複或衝突，開發者要先確認專案目前採用的規則。過期命令應從 AGENTS.md 更新，單次需求中的例外則要寫明適用範圍與原因。這能減少 Codex 在不同訊息之間猜測優先順序。

完成這次練習後，我們就能將一句模糊要求展開成可執行任務：交代目前情境、指定結果、限制修改範圍、保留既有行為、列出驗收條件及測試命令。Codex 的回覆也會因此更容易用程式差異和測試證據核對。